<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Create API key API | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="security-api.html" title="Security APIs">
<link rel="prev" href="security-api-clear-role-cache.html" title="Clear roles cache API">
<link rel="next" href="security-api-put-privileges.html" title="Create or update application privileges API">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="security-api.html">Security APIs</a></span>
»
<span class="breadcrumb-node">Create API key API</span>
</div>
<div class="navheader">
<span class="prev">
<a href="security-api-clear-role-cache.html">« Clear roles cache API</a>
</span>
<span class="next">
<a href="security-api-put-privileges.html">Create or update application privileges API »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="security-api-create-api-key"></a>Create API key API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc">edit</a><a class="xpack_tag" href="/subscriptions"></a>
</h2>
</div></div></div>

<p>Creates an API key for access without requiring basic authentication.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-create-api-key-request"></a>Request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc">edit</a>
</h3>
</div></div></div>
<p><code class="literal">POST /_security/api_key</code></p>
<p><code class="literal">PUT /_security/api_key</code></p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-create-api-key-prereqs"></a>Prerequisites<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
To use this API, you must have at least the <code class="literal">manage_api_key</code> cluster privilege.
</li>
</ul>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-create-api-key-desc"></a>Description<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The API keys are created by the Elasticsearch API key service, which is automatically enabled
when you configure TLS on the HTTP interface. See <a class="xref" href="configuring-tls.html#tls-http" title="Encrypting HTTP client communications">Encrypting HTTP client communications</a>. Alternatively,
you can explicitly enable the <code class="literal">xpack.security.authc.api_key.enabled</code> setting. When
you are running in production mode, a bootstrap check prevents you from enabling
the API key service unless you also enable TLS on the HTTP interface.</p>
<p>A successful create API key API call returns a JSON structure that contains the
API key, its unique id, and its name. If applicable, it also returns expiration
information for the API key in milliseconds.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>By default, API keys never expire. You can specify expiration information
when you create the API keys.</p>
</div>
</div>
<p>See <a class="xref" href="security-settings.html#api-key-service-settings" title="API key service settings">API key service settings</a> for configuration settings related to API key
service.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-create-api-key-request-body"></a>Request body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The following parameters can be specified in the body of a POST or PUT request:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">name</code>
</span>
</dt>
<dd>
(Required, string) Specifies the name for this API key.
</dd>
<dt>
<span class="term">
<code class="literal">role_descriptors</code>
</span>
</dt>
<dd>
(Optional, array-of-role-descriptor) An array of role descriptors for this API
key. This parameter is optional. When it is not specified or is an empty array,
then the API key will have a <em>point in time snapshot of permissions of the
authenticated user</em>. If you supply role descriptors then the resultant permissions
would be an intersection of API keys permissions and authenticated user’s permissions
thereby limiting the access scope for API keys.
The structure of role descriptor is the same as the request for create role API.
For more details, see <a class="xref" href="security-api-put-role.html" title="Create or update roles API">create or update roles API</a>.
</dd>
<dt>
<span class="term">
<code class="literal">expiration</code>
</span>
</dt>
<dd>
(Optional, string) Expiration time for the API key. By default, API keys never
expire.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-create-api-key-example"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The following example creates an API key:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/api_key
{
  "name": "my-api-key",
  "expiration": "1d", <a id="CO648-1"></a><i class="conum" data-value="1"></i>
  "role_descriptors": { <a id="CO648-2"></a><i class="conum" data-value="2"></i>
    "role-a": {
      "cluster": ["all"],
      "index": [
        {
          "names": ["index-a*"],
          "privileges": ["read"]
        }
      ]
    },
    "role-b": {
      "cluster": ["all"],
      "index": [
        {
          "names": ["index-b*"],
          "privileges": ["all"]
        }
      ]
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2065.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO648-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>optional expiration for the API key being generated. If expiration is not
provided then the API keys do not expire.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO648-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>optional role descriptors for this API key, if not provided then permissions
of authenticated user are applied.</p>
</td>
</tr>
</table>
</div>
<p>A successful call returns a JSON structure that provides
API key information.</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "id":"VuaCfGcBCdbkQm-e5aOx", <a id="CO649-1"></a><i class="conum" data-value="1"></i>
  "name":"my-api-key",
  "expiration":1544068612110, <a id="CO649-2"></a><i class="conum" data-value="2"></i>
  "api_key":"ui2lp2axTNmsyakw9tvNnw" <a id="CO649-3"></a><i class="conum" data-value="3"></i>
}</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO649-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>unique id for this API key</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO649-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>optional expiration in milliseconds for this API key</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO649-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>generated API key</p>
</td>
</tr>
</table>
</div>
<p>The API key returned by this API can then be used by sending a request with a
<code class="literal">Authorization</code> header with a value having the prefix <code class="literal">ApiKey</code> followed
by the <em>credentials</em>, where <em>credentials</em> is the base64 encoding of <code class="literal">id</code> and <code class="literal">api_key</code> joined by a colon.</p>
<div class="pre_wrapper lang-shell">
<pre class="programlisting prettyprint lang-shell">curl -H "Authorization: ApiKey VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==" http://localhost:9200/_cluster/health</pre>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="security-api-clear-role-cache.html">« Clear roles cache API</a>
</span>
<span class="next">
<a href="security-api-put-privileges.html">Create or update application privileges API »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
